Documentation
¶
Overview ¶
Package presetref parses and classifies a preset reference — the string in a `preset:` field that locates a preset fragment, optionally from a remote source at a git ref. Classification decides how the loader resolves it (local read, live fetch, or cache-authoritative), per the identity model's preset-resolution design. This is pure parsing and static classification — no I/O; the one genuinely source-dependent case (a bare ref name that could be a branch or a tag) is marked Named and left for the fetch layer to resolve against the source.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
Types ¶
type Cache ¶
Cache is the retention store for fetched presets — the fallback for tracked refs and the authoritative store for pinned refs. Keyed by a ref's CacheKey.
type FSCache ¶
type FSCache struct {
Root string
}
FSCache is a filesystem-backed Cache rooted at a directory — typically a repo's .stagefreight/preset-cache. It stores each fetched preset under its (sanitized, slash-bearing but ..-free) CacheKey, so pinned refs and tracked-ref fallbacks persist across runs.
type FetchMode ¶
type FetchMode int
FetchMode controls network behavior.
const ( // FetchLive is the default: a tracked ref is fetched each run (cache as fallback); a // pinned ref is served from cache if present, else fetched once. FetchLive FetchMode = iota // FetchOffline never touches the network: everything resolves from cache, and a miss // is an error. For air-gapped CI running against a pre-seeded cache. FetchOffline )
type Fetcher ¶
type Fetcher interface {
// Fetch returns the file at path from source at ref (ref "" = the default branch).
Fetch(source, ref, path string) ([]byte, error)
// Classify resolves a BARE Named ref against the source: a tag → Pinned, a branch →
// Tracked. Called only for Named refs.
Classify(source, ref string) (Kind, error)
}
Fetcher does the actual remote I/O for a preset source; the Resolver stays pure policy over it, so the tracked/pinned/fallback logic is testable without a network.
type Kind ¶
type Kind int
Kind is how a preset reference resolves.
const ( // Local is an in-repo path (no source): read from the working tree / preset-cache. Local Kind = iota // Tracked is a source at a branch (or no ref): fetched live each run so a change at // the source propagates to every tracking repo, with the cache as offline fallback. Tracked // Pinned is a source at a provably-immutable ref (a sha or a refs/tags/ tag): // cache-authoritative — resolved from cache when present, fetched once otherwise. Pinned // Named is a source at a BARE ref name (e.g. "main", "v1.0") that can't be classified // statically — a branch and a tag look identical as strings. The fetch layer resolves // it against the source (a tag → pinned, a branch → tracked). Pinning explicitly // (a sha or refs/tags/…) avoids this deferral. Named )
type Ref ¶
type Ref struct {
Raw string // the original string
Kind Kind
Source string // "<source>" (forge repo or URL); "" for Local
Path string // preset path within the source, or the local path for Local
Ref string // the git ref (branch / tag / sha, possibly refs/-qualified); "" = default branch
}
Ref is a parsed preset reference.
func Parse ¶
Parse classifies a preset reference. Forms:
preset/lint.yml → Local gitlab:Org/Repo//preset/lint.yml → Tracked (default branch) …//preset/lint.yml@main → Named (bare — resolved at fetch) …//preset/lint.yml@refs/heads/main → Tracked …//preset/lint.yml@refs/tags/v1.0 → Pinned …//preset/lint.yml@v1.0 → Named (bare — resolved at fetch) …//preset/lint.yml@1a2b3c4 → Pinned (sha)
type Resolver ¶
type Resolver struct {
Fetcher Fetcher
Cache Cache
Mode FetchMode
// Warnf, if set, reports a non-fatal condition (e.g. a stale-cache fallback).
Warnf func(format string, args ...any)
}
Resolver resolves a SOURCED preset Ref (Tracked/Pinned/Named) to its content, applying the source-tracking policy. Local refs are out of scope — the local loader handles them.
Source Files