Documentation
¶
Overview ¶
Package versions stores retained gridctl binaries under a home-scoped directory so a standalone install can roll back without a download.
Layout: manifest.json (0644), .lock, and <tag>/gridctl (0755). The store knows nothing about GitHub, tarballs, or daemons. Callers copy a file in with Retain and install it themselves.
Index ¶
- Constants
- Variables
- func ValidateTag(tag string) error
- type Entry
- type Manifest
- type Schemas
- type Store
- func (s *Store) Active() string
- func (s *Store) AllowSources(paths ...string)
- func (s *Store) Close() error
- func (s *Store) Entries() []Entry
- func (s *Store) Lookup(tag string) (Entry, string, bool)
- func (s *Store) Orphans() []string
- func (s *Store) Previous() string
- func (s *Store) Prune(ctx context.Context, keep int) ([]string, error)
- func (s *Store) Retain(ctx context.Context, tag, srcPath, origin string, schemas *Schemas) error
- func (s *Store) SetActive(active, previous string) error
- func (s *Store) Verify(ctx context.Context, tag string) error
Constants ¶
const ( // OriginReplaced marks a binary copied from the executable that was // about to be replaced. OriginReplaced = "replaced" // OriginDownloaded marks a binary copied from a verified release archive. OriginDownloaded = "downloaded" )
const ( // ManifestSchemaVersion is the current manifest schema. A newer // value is refused rather than rewritten (Article XVII). ManifestSchemaVersion = 1 )
Variables ¶
var ( // ErrNewerManifest marks a manifest written by a newer gridctl. // Callers must not rewrite it. ErrNewerManifest = errors.New("versions manifest written by a newer gridctl") // ErrChecksumMismatch marks a retained binary whose SHA256 does not // match the manifest. The installed binary must not be replaced. ErrChecksumMismatch = errors.New("retained binary checksum mismatch") // ErrInvalidTag marks a tag that is not safe to use as a single // directory name under the store. ErrInvalidTag = errors.New("invalid version tag") // ErrSymlinkSource marks a retain source that is a symlink resolving // outside the allowed temp directory or executable path. ErrSymlinkSource = errors.New("retain source symlink resolves outside allowed paths") )
Functions ¶
func ValidateTag ¶
ValidateTag reports whether tag is a single directory name with no separator and no "..". Rollback callers also require a semver tag.
Types ¶
type Entry ¶
type Entry struct {
Tag string `json:"tag"`
SHA256 string `json:"sha256"`
Size int64 `json:"size"`
RetainedAt time.Time `json:"retained_at"`
Origin string `json:"origin"`
Schemas *Schemas `json:"schemas"`
}
Entry is one retained binary.
type Manifest ¶
type Manifest struct {
SchemaVersion int `json:"schema_version"`
Active string `json:"active"`
Previous string `json:"previous"`
Entries []Entry `json:"entries"`
}
Manifest is the on-disk index. Active is the tag last installed. Previous is the tag to restore when rollback is given no tag.
type Schemas ¶
type Schemas struct {
DaemonState int `json:"daemon_state"`
ProjectLock int `json:"project_lock"`
ImportLock int `json:"import_lock"`
ToolPins string `json:"tool_pins"`
SkillPins string `json:"skill_pins"`
PinApprovals string `json:"pin_approvals"`
ContextPins string `json:"context_pins"`
}
Schemas is the schema advertisement a binary reported at retention time. Nil means the retaining release did not record one (serialized as null). Pin fields are strings because the on-disk constants are strings; an absent pin field decodes as "".
type Store ¶
type Store struct {
// contains filtered or unexported fields
}
Store is an exclusively locked versions directory. Close releases the lock.
func Open ¶
Open creates dir (0755) if needed and acquires a cross-process exclusive flock on .lock. A manifest with schema_version greater than ManifestSchemaVersion returns ErrNewerManifest and does not hold the lock. A missing manifest is an empty store.
func (*Store) AllowSources ¶
AllowSources records files and directories a symlink retain source may resolve into. A symlink that resolves outside every allowed path is refused. A regular file is accepted. When no sources have been allowed, every symlink is refused.
func (*Store) Lookup ¶
Lookup returns the entry and the binary path. ok is false when the tag is not in the manifest. The file may be missing until the next write drops the entry.
func (*Store) Orphans ¶
Orphans returns directory names present on disk but absent from the manifest, sorted. They are never deleted.
func (*Store) Prune ¶
Prune removes oldest RetainedAt entries first until the count is at or below keep. Active and Previous are never removed, so the floor can exceed keep. Removed tags are returned. Directories that are not in the manifest are left in place (see Orphans).
func (*Store) Retain ¶
Retain copies srcPath into <tag>/gridctl through a temp sibling and rename, then upserts the entry. Re-retaining an existing tag with the same SHA256 is a no-op. A different SHA256 replaces the file and entry. On every write, entries whose file is missing are dropped from the manifest.
Source Files