actionscache

package

v0.4.2 Latest Latest Go to latest Published: Oct 17, 2026 License: MIT Imports: 17 Imported by: 0

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/bnema/ermite-runner

Links

Open Source Insights

Documentation ¶

Overview ¶

Package actionscache is the host-side cache of action archives (plan CI-4, D8). The host downloads the tarball of an action once per (repository, resolved commit) and every job, in any sandbox, is served the same bytes through the cache channel (see cachesvc): the forge is hit once, not once per job (codeload answered 429 during the CI-3 compare).

An entry is keyed by Key: a hash of the forge, the repository and the resolved commit sha. A mutable ref (a tag, a branch) is never part of it, so a moved tag cannot serve stale bytes: the server resolves the ref to a sha at each job.

The bytes come from the host's own download, never from a sandbox: the guest runs untrusted code and must not be able to plant an archive that other jobs would run. Each entry is two files in Dir, <key>.tgz and <key>.sum (the sha256 and the size of the archive). The sum is written after the archive, so an archive without one is a crash leftover and is removed at start. Every read re-hashes the archive; a mismatch drops the entry and the caller downloads it again.

The total size is capped; the least recently used entries go first. An entry handed out is pinned for a while (PinFor), so that it cannot be evicted between the host fetching it and the sandbox reading it.

Index ¶

Constants
Variables
func Key(origin, repo, sha string) (key string, ok bool)
func NewClient(base *http.Client) *http.Client
func ParseMax(v string) (int64, error)
func ValidKey(k string) bool
type Cache
- func New(cfg Config) (*Cache, error)
type Config
type Fetch

Constants ¶

View Source

const (
	// DefaultMax is the size cap when ERMITE_RUNNER_ACTIONS_CACHE_MAX is unset.
	DefaultMax = 2 << 30
	// EnvMax is ERMITE_RUNNER_ACTIONS_CACHE_MAX: a size (2G, 500M…); 0 turns the
	// cache off.
	EnvMax = "ERMITE_RUNNER_ACTIONS_CACHE_MAX"
	// PinFor is how long a served entry is protected from eviction.
	PinFor = 30 * time.Minute
)

Defaults and names.

Variables ¶

View Source

var ErrNotFound = errors.New("actionscache: no such entry")

ErrNotFound is an entry that is absent, corrupt or evicted.

View Source

var ErrTooLarge = errors.New("actionscache: archive larger than the cache")

ErrTooLarge is an archive that does not fit under the cap on its own.

Functions ¶

func Key ¶

func Key(origin, repo, sha string) (key string, ok bool)

Key is the entry key of an archive: the sha256 of the forge origin, the repository and the resolved commit. ok is false when sha is not a full git object name (40 or 64 hex digits): such an archive is not cached, whatever the ref said.

func NewClient ¶

func NewClient(base *http.Client) *http.Client

NewClient returns the client that downloads the archives. It follows redirects (GitHub's codeload does redirect) but never carries credentials across an origin: the Authorization header is dropped as soon as the scheme, the host or the port changes, and a redirect from https to http is refused. (net/http alone would keep the header for subdomains and ignore the scheme and the port.) Tests may supply their own transport through Actions.HTTPClient; its redirect policy is replaced.

func ParseMax ¶

func ParseMax(v string) (int64, error)

ParseMax reads ERMITE_RUNNER_ACTIONS_CACHE_MAX: empty is DefaultMax, 0 is off (returned as 0), otherwise a number of bytes or a size with a K, M, G or T suffix (optionally followed by iB or B).

func ValidKey ¶

func ValidKey(k string) bool

ValidKey reports whether k has the shape of a Key.

Types ¶

type Cache ¶

type Cache struct {
	// contains filtered or unexported fields
}

Cache is the archive cache.

func New ¶

func New(cfg Config) (*Cache, error)

New opens (and creates) dir, forgetting what a crash left half written.

func (*Cache) Dir ¶

func (c *Cache) Dir() string

Dir is the directory of the cache (tests).

func (*Cache) Ensure ¶

func (c *Cache) Ensure(ctx context.Context, key string, fetch Fetch) (hit bool, err error)

Ensure makes sure the entry of key exists and is intact, calling fetch to download it when it does not (a miss: hit is false). Concurrent calls for the same key share one download; the others report a hit once it is in place. The entry is pinned for PinFor.

func (*Cache) Open ¶

func (c *Cache) Open(key string) (*os.File, error)

Open returns the verified archive of key. The caller closes it.

func (*Cache) Size ¶

func (c *Cache) Size() int64

Size is the bytes held (tests, logs).

type Config ¶

type Config struct {
	Dir string
	// Max is the size cap in bytes, > 0.
	Max int64
	Now func() time.Time
	Log zerowrap.Logger
}

Config configures a Cache.

type Fetch ¶

type Fetch func(ctx context.Context, w io.Writer) error

Fetch writes an archive to w; it is called at most once at a time per key.

Source Files ¶

View all Source files

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL