|
| 1 | +package checkpoint |
| 2 | + |
| 3 | +import ( |
| 4 | + "context" |
| 5 | + "errors" |
| 6 | + "sort" |
| 7 | + |
| 8 | + "github.com/entireio/cli/cmd/entire/cli/checkpoint/id" |
| 9 | +) |
| 10 | + |
| 11 | +// kindRoutingStore resolves id-keyed reads across the two git backends so a repo |
| 12 | +// running git-refs and git-branch side by side (or mid-migration between them) |
| 13 | +// can read checkpoints of BOTH formats without reconfiguring: |
| 14 | +// |
| 15 | +// - A ULID checkpoint only ever lives in the git-refs store, so a ULID ID is |
| 16 | +// read from refs and NEVER from the branch (regardless of the active backend). |
| 17 | +// - A legacy-hex ID is read from the active (configured) primary first. When the |
| 18 | +// active primary is git-refs, it also falls back to the git-branch store, |
| 19 | +// because a hex checkpoint may still sit on the pre-migration v1 branch. Under |
| 20 | +// a git-branch primary the branch is authoritative for hex, so refs is not |
| 21 | +// consulted. |
| 22 | +// |
| 23 | +// List unions both backends (disjoint ID spaces). Writes are NOT kind-routed: |
| 24 | +// they go to the configured primary (+ mirrors) via writer, since a new |
| 25 | +// checkpoint's ID is already minted to match the primary's format |
| 26 | +// (see checkpoint.GenerateCheckpointID). |
| 27 | +type kindRoutingStore struct { |
| 28 | + writer PersistentStore // configured primary + mirrors (fanout); handles Write |
| 29 | + branch PersistentStore // git-branch store; serves hex reads |
| 30 | + refs PersistentStore // git-refs store; serves ULID reads (+ hex under refs primary) |
| 31 | + primaryType string |
| 32 | +} |
| 33 | + |
| 34 | +// newKindRoutingStore wraps the write fanout plus the two git read stores. It |
| 35 | +// preserves the optional AuthorReader capability (explain relies on it) when both |
| 36 | +// read stores provide it — the built-in git backends always do. |
| 37 | +func newKindRoutingStore(writer, branch, refs PersistentStore, primaryType string) PersistentStore { |
| 38 | + s := &kindRoutingStore{writer: writer, branch: branch, refs: refs, primaryType: primaryType} |
| 39 | + if _, ok := branch.(AuthorReader); ok { |
| 40 | + if _, ok := refs.(AuthorReader); ok { |
| 41 | + return &kindRoutingStoreWithAuthor{kindRoutingStore: s} |
| 42 | + } |
| 43 | + } |
| 44 | + return s |
| 45 | +} |
| 46 | + |
| 47 | +// readOrder returns the stores to consult for checkpointID, in priority order, |
| 48 | +// per the routing rules above. |
| 49 | +func (s *kindRoutingStore) readOrder(checkpointID id.CheckpointID) []PersistentStore { |
| 50 | + if checkpointID.Kind() == id.KindULID { |
| 51 | + return []PersistentStore{s.refs} // ULIDs only ever live in refs |
| 52 | + } |
| 53 | + switch s.primaryType { |
| 54 | + case BackendTypeGitBranch: |
| 55 | + return []PersistentStore{s.branch} // branch is authoritative for hex |
| 56 | + case BackendTypeGitRefs: |
| 57 | + return []PersistentStore{s.refs, s.branch} // active refs, then pre-migration branch |
| 58 | + default: |
| 59 | + // A non-branch/refs git-backed primary is not a real configuration today; |
| 60 | + // try both git stores so a hex ID still resolves wherever it landed. |
| 61 | + return []PersistentStore{s.branch, s.refs} |
| 62 | + } |
| 63 | +} |
| 64 | + |
| 65 | +// firstResolved calls read on each store in order and returns the first genuine |
| 66 | +// hit (a non-absent result with no error). A non-final store that reports absent |
| 67 | +// OR errors falls through to the next store, so a transient failure in one |
| 68 | +// backend (e.g. a git-refs on-demand fetch error) does not hide a checkpoint that |
| 69 | +// resolves in the fallback backend. The final store's result is returned as-is |
| 70 | +// (hit, absent, or error), so callers still see the backend's own not-found / |
| 71 | +// error signal when nothing resolved. |
| 72 | +func firstResolved[T any](stores []PersistentStore, read func(PersistentStore) (T, error), absent func(T, error) bool) (T, error) { |
| 73 | + var v T |
| 74 | + var err error |
| 75 | + for i, st := range stores { |
| 76 | + v, err = read(st) |
| 77 | + if i == len(stores)-1 || (err == nil && !absent(v, err)) { |
| 78 | + return v, err |
| 79 | + } |
| 80 | + } |
| 81 | + return v, err |
| 82 | +} |
| 83 | + |
| 84 | +// checkpointNotFound reports the checkpoint-level "absent" signal: Read returns |
| 85 | +// (nil, nil) — not an error — when a checkpoint does not exist. |
| 86 | +func checkpointNotFound(v *CheckpointSummary, err error) bool { |
| 87 | + return err == nil && v == nil |
| 88 | +} |
| 89 | + |
| 90 | +// sessionNotFound reports the session-level "absent" signal: the session readers |
| 91 | +// return ErrCheckpointNotFound when the checkpoint (or session) is missing. |
| 92 | +func sessionNotFound[T any](_ T, err error) bool { |
| 93 | + return errors.Is(err, ErrCheckpointNotFound) |
| 94 | +} |
| 95 | + |
| 96 | +func (s *kindRoutingStore) Read(ctx context.Context, checkpointID id.CheckpointID) (*CheckpointSummary, error) { |
| 97 | + return firstResolved(s.readOrder(checkpointID), |
| 98 | + func(st PersistentStore) (*CheckpointSummary, error) { return st.Read(ctx, checkpointID) }, |
| 99 | + checkpointNotFound, |
| 100 | + ) |
| 101 | +} |
| 102 | + |
| 103 | +func (s *kindRoutingStore) List(ctx context.Context) ([]CheckpointInfo, error) { |
| 104 | + branchList, err := s.branch.List(ctx) |
| 105 | + if err != nil { |
| 106 | + return nil, err //nolint:wrapcheck // in-package store error surfaced verbatim |
| 107 | + } |
| 108 | + refsList, err := s.refs.List(ctx) |
| 109 | + if err != nil { |
| 110 | + return nil, err //nolint:wrapcheck // in-package store error surfaced verbatim |
| 111 | + } |
| 112 | + merged := make([]CheckpointInfo, 0, len(branchList)+len(refsList)) |
| 113 | + merged = append(merged, branchList...) |
| 114 | + merged = append(merged, refsList...) |
| 115 | + sortCheckpointInfosByRecency(merged) |
| 116 | + // Dedup by ID: during coexistence/migration the same checkpoint can appear in |
| 117 | + // both backends (a ULID mirrored to the branch, or a hex still on the branch |
| 118 | + // and also migrated into refs). Keep the first occurrence — i.e. the most |
| 119 | + // recent after the sort. |
| 120 | + deduped := merged[:0] |
| 121 | + seen := make(map[id.CheckpointID]struct{}, len(merged)) |
| 122 | + for _, info := range merged { |
| 123 | + if _, dup := seen[info.CheckpointID]; dup { |
| 124 | + continue |
| 125 | + } |
| 126 | + seen[info.CheckpointID] = struct{}{} |
| 127 | + deduped = append(deduped, info) |
| 128 | + } |
| 129 | + return deduped, nil |
| 130 | +} |
| 131 | + |
| 132 | +// sortCheckpointInfosByRecency orders checkpoints most-recent-first by CreatedAt. |
| 133 | +// Shared by the git-branch, git-refs, and routing List implementations so they |
| 134 | +// present a consistent order. |
| 135 | +func sortCheckpointInfosByRecency(checkpoints []CheckpointInfo) { |
| 136 | + sort.Slice(checkpoints, func(i, j int) bool { |
| 137 | + return checkpoints[i].CreatedAt.After(checkpoints[j].CreatedAt) |
| 138 | + }) |
| 139 | +} |
| 140 | + |
| 141 | +func (s *kindRoutingStore) ReadSessionContent(ctx context.Context, checkpointID id.CheckpointID, sessionIndex int) (*SessionContent, error) { |
| 142 | + return firstResolved(s.readOrder(checkpointID), |
| 143 | + func(st PersistentStore) (*SessionContent, error) { |
| 144 | + return st.ReadSessionContent(ctx, checkpointID, sessionIndex) |
| 145 | + }, |
| 146 | + sessionNotFound[*SessionContent], |
| 147 | + ) |
| 148 | +} |
| 149 | + |
| 150 | +func (s *kindRoutingStore) ReadSessionMetadata(ctx context.Context, checkpointID id.CheckpointID, sessionIndex int) (*Metadata, error) { |
| 151 | + return firstResolved(s.readOrder(checkpointID), |
| 152 | + func(st PersistentStore) (*Metadata, error) { |
| 153 | + return st.ReadSessionMetadata(ctx, checkpointID, sessionIndex) |
| 154 | + }, |
| 155 | + sessionNotFound[*Metadata], |
| 156 | + ) |
| 157 | +} |
| 158 | + |
| 159 | +func (s *kindRoutingStore) ReadSessionPrompts(ctx context.Context, checkpointID id.CheckpointID, sessionIndex int) (string, error) { |
| 160 | + return firstResolved(s.readOrder(checkpointID), |
| 161 | + func(st PersistentStore) (string, error) { |
| 162 | + return st.ReadSessionPrompts(ctx, checkpointID, sessionIndex) |
| 163 | + }, |
| 164 | + sessionNotFound[string], |
| 165 | + ) |
| 166 | +} |
| 167 | + |
| 168 | +// metaAndPrompts bundles the two non-error returns of ReadSessionMetadataAndPrompts |
| 169 | +// so it can flow through the single-value firstResolved helper. |
| 170 | +type metaAndPrompts struct { |
| 171 | + meta *Metadata |
| 172 | + prompts string |
| 173 | +} |
| 174 | + |
| 175 | +func (s *kindRoutingStore) ReadSessionMetadataAndPrompts(ctx context.Context, checkpointID id.CheckpointID, sessionIndex int) (*Metadata, string, error) { |
| 176 | + mp, err := firstResolved(s.readOrder(checkpointID), |
| 177 | + func(st PersistentStore) (metaAndPrompts, error) { |
| 178 | + m, p, e := st.ReadSessionMetadataAndPrompts(ctx, checkpointID, sessionIndex) |
| 179 | + return metaAndPrompts{meta: m, prompts: p}, e //nolint:wrapcheck // in-package store error surfaced verbatim |
| 180 | + }, |
| 181 | + sessionNotFound[metaAndPrompts], |
| 182 | + ) |
| 183 | + return mp.meta, mp.prompts, err |
| 184 | +} |
| 185 | + |
| 186 | +// Write is not kind-routed: it targets the configured primary (+ mirrors). |
| 187 | +func (s *kindRoutingStore) Write(ctx context.Context, req WriteRequest) error { |
| 188 | + return s.writer.Write(ctx, req) //nolint:wrapcheck // primary error is the operation's error, surfaced verbatim |
| 189 | +} |
| 190 | + |
| 191 | +// kindRoutingStoreWithAuthor adds the optional AuthorReader capability, routing |
| 192 | +// GetCheckpointAuthor by the same rules as the reads. |
| 193 | +type kindRoutingStoreWithAuthor struct { |
| 194 | + *kindRoutingStore |
| 195 | +} |
| 196 | + |
| 197 | +func (s *kindRoutingStoreWithAuthor) GetCheckpointAuthor(ctx context.Context, checkpointID id.CheckpointID) (Author, error) { |
| 198 | + return firstResolved(s.readOrder(checkpointID), |
| 199 | + func(st PersistentStore) (Author, error) { |
| 200 | + ar, ok := st.(AuthorReader) |
| 201 | + if !ok { |
| 202 | + return Author{}, nil |
| 203 | + } |
| 204 | + return ar.GetCheckpointAuthor(ctx, checkpointID) |
| 205 | + }, |
| 206 | + func(a Author, err error) bool { return err == nil && a == Author{} }, |
| 207 | + ) |
| 208 | +} |
0 commit comments