Documentation
¶
Overview ¶
Package sourcecache keeps a bounded bare mirror of every repository the control plane fetches, so a known commit never needs the git host again.
Index ¶
- Constants
- Variables
- func IsOffline(ctx context.Context) bool
- func IsUnreachable(err error) bool
- func ProbeInterval() time.Duration
- func WithOffline(ctx context.Context) context.Context
- type Cache
- func (c *Cache) Block(repoURL, key string)
- func (c *Cache) Checkout(ctx context.Context, repoURL, ref, token string) (Checkout, error)
- func (c *Cache) MirrorSize(repoURL string) int64
- func (c *Cache) OpenMirror(repoURL string) (repo *git.Repository, size func() int64, release func(), err error)
- func (c *Cache) Prune(now time.Time) ([]string, error)
- func (c *Cache) Reachable(ctx context.Context, repoURL string) bool
- func (c *Cache) RecoverOnce(ctx context.Context, ...)
- func (c *Cache) ResetMirror(repoURL string) error
- func (c *Cache) Unreachable() []HostStatus
- func (c *Cache) Watch(ctx context.Context, interval time.Duration, ...)
- type Checkout
- type Config
- type HostStatus
Constants ¶
const ( EnvMaxBytes = "APP_SOURCE_CACHE_MAX_BYTES" EnvMaxAge = "APP_SOURCE_CACHE_MAX_AGE" EnvFetchTimeout = "APP_GIT_FETCH_TIMEOUT" EnvRetries = "APP_GIT_FETCH_RETRIES" EnvBackoff = "APP_GIT_FETCH_BACKOFF" EnvProbeEvery = "APP_GIT_RECOVERY_INTERVAL" DefaultMaxBytes int64 = 5 << 30 DefaultMaxAge = 30 * 24 * time.Hour DefaultFetchTimeout = 10 * time.Minute DefaultRetries = 2 DefaultBackoff = 2 * time.Second DefaultProbeEvery = 30 * time.Second )
Environment variables and defaults for the cache and the fetches that fill it.
Variables ¶
var ( // ErrHostUnreachable marks a fetch that could not reach the git host and // found the wanted commit nowhere in the mirror. ErrHostUnreachable = errors.New("git host unreachable, commit not cached") // ErrNotCached marks an offline checkout of a ref the mirror lacks. ErrNotCached = errors.New("not in the source cache, git host not contacted") // ErrCommitNotFound marks a ref the repository does not have. ErrCommitNotFound = errors.New("commit not found") )
var ErrNoMirrorDir = errors.New("sourcecache: no mirror directory configured")
ErrNoMirrorDir means the cache keeps no mirror, so pushed objects would be lost.
Functions ¶
func IsUnreachable ¶
IsUnreachable reports whether err means the host could not be reached or is failing server-side, as opposed to rejecting the request (auth, missing repository), which a retry cannot fix.
func ProbeInterval ¶
ProbeInterval is how often unreachable hosts are re-checked.
Types ¶
type Cache ¶
type Cache struct {
// contains filtered or unexported fields
}
Cache is the bounded source mirror plus the git host health it observes.
func (*Cache) Block ¶
Block records that key (an app name) could not deploy because host is down, so it can be retried when the host recovers. No-op for a healthy host.
func (*Cache) Checkout ¶
Checkout materializes ref of repoURL into a fresh temp directory. A full commit hash already in the mirror never touches the network. Any other ref is refreshed first, so a moved branch is never served stale; when the host is down that fails with ErrHostUnreachable. Under WithOffline only the mirror is read.
func (*Cache) MirrorSize ¶
MirrorSize is the bytes on disk the mirror for repoURL holds, 0 when absent.
func (*Cache) OpenMirror ¶
func (c *Cache) OpenMirror(repoURL string) (repo *git.Repository, size func() int64, release func(), err error)
OpenMirror opens, creating if needed, the bare mirror for repoURL and marks it in use until release runs. A pushed commit stored here is later checked out by hash with no network call. size reports the mirror's bytes on disk.
func (*Cache) Prune ¶
Prune removes mirrors unused for longer than MaxAge, then the least recently used ones until the total fits MaxBytes. Mirrors with a live checkout are never removed. Order is (last used, name), so the same directory state always prunes the same way. It returns the removed names.
func (*Cache) Reachable ¶
Reachable asks the host for its ref list. An auth or not-found answer still means the host is up.
func (*Cache) RecoverOnce ¶
func (c *Cache) RecoverOnce(ctx context.Context, onRecover func(ctx context.Context, host string, blocked []string))
RecoverOnce is one Watch pass.
func (*Cache) ResetMirror ¶
ResetMirror deletes the mirror for repoURL. Callers must hold no OpenMirror handle for it.
func (*Cache) Unreachable ¶
func (c *Cache) Unreachable() []HostStatus
Unreachable lists the hosts whose last fetch failed, sorted by host.
func (*Cache) Watch ¶
func (c *Cache) Watch(ctx context.Context, interval time.Duration, onRecover func(ctx context.Context, host string, blocked []string))
Watch probes every failing host each interval until ctx ends. A host that answers is cleared and onRecover gets the keys that were blocked on it.
type Checkout ¶
type Checkout struct {
Dir string
Commit string
// FromCache is true when no network call was made.
FromCache bool
// contains filtered or unexported fields
}
Checkout is a source tree materialized from the mirror. Cleanup removes the working tree and releases the mirror for pruning.
type Config ¶
type Config struct {
Dir string
MaxBytes int64
MaxAge time.Duration
FetchTimeout time.Duration
Retries int
Backoff time.Duration
}
Config bounds the mirror and the network calls made to fill it. An empty Dir keeps no mirror: every checkout is a fresh, throwaway fetch.
func ConfigFromEnv ¶
ConfigFromEnv reads the cache and fetch limits from the environment; a malformed or non-positive value falls back to its default.
Source Files