cachefact

type Body ¶

type Body interface {
	FactKind() Kind
}

Body is the kind-specific content of a fact.

type Boot ¶

type Boot string

Boot says whether an engine started with an empty cache or restored one.

const (
	BootFresh    Boot = "fresh"
	BootRestored Boot = "restored"
)

type Class ¶

type Class struct {
	Digests []Digest `json:"digests"`
}

Class announces one equivalence class restored at boot, with every digest of the class.

func (Class) FactKind() Kind

type Deps ¶

type Deps struct {
	ID       uint64   `json:"id"`
	Deps     []uint64 `json:"deps"`
	Complete bool     `json:"complete"`
}

Deps gives a computed result's complete dependency set. A later Deps fact for the same result replaces the earlier set.

func (Deps) FactKind() Kind

type Digest ¶

type Digest struct {
	Digest string `json:"digest"`
	Label  string `json:"label"`
}

Digest is one digest with its label.

For a digest posting the label is LabelRecipe for a call's recipe digest, and the extra digest's own label otherwise (for example "content" or "remote-cache"). An extra digest recorded without a label has an empty label.

type EngineAlive ¶

type EngineAlive struct {
	// DroppedFacts counts facts the engine dropped since it started. A
	// non-zero count means the fact stream of this instance is incomplete.
	DroppedFacts uint64 `json:"droppedFacts"`
}

EngineAlive is emitted periodically while the engine runs.

func (EngineAlive) FactKind() Kind

type EngineStart ¶

type EngineStart struct {
	EngineVersion string `json:"engineVersion"`
	EngineName    string `json:"engineName"`
	Boot          Boot   `json:"boot"`
	// RestoredResults is the number of results the boot restore installed.
	RestoredResults int `json:"restoredResults"`
	// CloudEngineID is the Dagger Cloud engine ID, when the environment names
	// one.
	CloudEngineID string `json:"cloudEngineId,omitempty"`
}

EngineStart is emitted once per engine process, after the cache's boot restore finished.

func (EngineStart) FactKind() Kind

type EngineStop ¶

type EngineStop struct {
	PersistedResults int  `json:"persistedResults"`
	Clean            bool `json:"clean"`
}

EngineStop is emitted on graceful shutdown, after the cache persisted its state.

func (EngineStop) FactKind() Kind

type Fact ¶

type Fact struct {
	Seq  uint64
	Body Body
}

Fact is one cache fact: its sequence number and its body. Body holds a value of one of this package's body types, never a pointer; decoding produces values.

Its JSON form is one flat object: "seq" and "kind" followed by the body's fields.

func Decode(data []byte) (Fact, error)

func (f Fact) Kind() Kind

func (f Fact) MarshalJSON() ([]byte, error)

func (f *Fact) UnmarshalJSON(data []byte) error

type Identity ¶

type Identity struct {
	ID uint64 `json:"id"`
	// Digests are the digest postings this teach added to the result. It can
	// be empty when the teach merged classes without adding a posting.
	Digests []Digest `json:"digests"`
	// Term is the term the teach used; TermUse says how.
	Term    Term    `json:"term"`
	TermUse TermUse `json:"termUse"`
	// ExpiresAtUnix is the result's own expiry after the teach (0: none).
	ExpiresAtUnix int64 `json:"expiresAtUnix"`
}

Identity records digests and a term taught onto an existing result, for example on a cache hit or when a content digest is learned.

func (Identity) FactKind() Kind

type Kind ¶

type Kind string

Kind names the kind of a fact.

const (
	KindEngineStart Kind = "engine.start"
	KindEngineAlive Kind = "engine.alive"
	KindEngineStop  Kind = "engine.stop"
	KindResult      Kind = "result"
	KindClass       Kind = "class"
	KindTerm        Kind = "term"
	KindDeps        Kind = "deps"
	KindIdentity    Kind = "identity"
	KindRetention   Kind = "retention"
	KindPart        Kind = "part"
	KindRemoved     Kind = "removed"
)

type Origin ¶

type Origin string

Origin is how a result entered the engine's cache.

const (
	// OriginComputed is a result the engine computed or attached itself.
	OriginComputed Origin = "computed"
	// OriginImported is a result imported from a value bundle.
	OriginImported Origin = "imported"
	// OriginRestored is a result restored from the engine's persisted cache
	// at boot.
	OriginRestored Origin = "restored"
)

type Part ¶

type Part struct {
	ID uint64 `json:"id"`
	// OutputPath is the path of the output inside the result's value, empty
	// for the value itself.
	OutputPath string `json:"outputPath"`
	Part       string `json:"part"`
	State      string `json:"state"`
}

Part records a state change of one filesystem part of a result.

func (Part) FactKind() Kind

type Provenance ¶

type Provenance string

Provenance is how a term input was known when the term was associated: as a result, or as a digest only.

const (
	ProvenanceResult Provenance = "result"
	ProvenanceDigest Provenance = "digest"
)

type Removed ¶

type Removed struct {
	IDs    []uint64      `json:"ids"`
	Reason RemovedReason `json:"reason"`
}

Removed lists results that left the cache in one critical section.

func (Removed) FactKind() Kind

type RemovedReason ¶

type RemovedReason string

RemovedReason says why results left the cache.

const (
	// RemovedSessionRelease: a released session owned the last reference.
	RemovedSessionRelease RemovedReason = "session_release"
	// RemovedPrune: a prune dropped the retention edge that owned the last
	// reference.
	RemovedPrune RemovedReason = "prune"
	// RemovedRollback: publication of a freshly registered result failed.
	RemovedRollback RemovedReason = "rollback"
	// RemovedReleased: any other release of the last reference, for example
	// the end of a call's publication hold or of an export's hold.
	RemovedReleased RemovedReason = "released"
)

type Result ¶

type Result struct {
	ID         uint64   `json:"id"`
	Origin     Origin   `json:"origin"`
	Field      string   `json:"field"`
	TypeName   string   `json:"typeName"`
	RecordType string   `json:"recordType"`
	Digests    []Digest `json:"digests"`
	Terms      []Term   `json:"terms"`

	CreatedAtUnixNano int64 `json:"createdAtUnixNano"`
	// ExpiresAtUnix is the result's own expiry (0: none). It bounds when the
	// result can serve as a cache hit.
	ExpiresAtUnix int64 `json:"expiresAtUnix"`

	Deps     []uint64 `json:"deps,omitempty"`
	Retained bool     `json:"retained,omitempty"`
	// RetentionExpiresAtUnix is the retention edge's expiry (0: none).
	RetentionExpiresAtUnix int64 `json:"retentionExpiresAtUnix,omitempty"`
	Unpruneable            bool  `json:"unpruneable,omitempty"`
}

Result announces a result registered in the cache under a new result number.

For OriginComputed and OriginImported, Digests are the result's exact digest postings and Terms the terms the result is associated with. For OriginRestored, Digests hold one representative digest per output equivalence class and Terms is empty; the classes and terms themselves are announced by the Class and TermFact facts that precede the restored results.

Deps and the retention fields are set for OriginImported and OriginRestored only. A computed result's dependencies and retention follow in their own Deps and Retention facts.

func (Result) FactKind() Kind

type Retention ¶

type Retention struct {
	ID       uint64 `json:"id"`
	Retained bool   `json:"retained"`
	// ExpiresAtUnix is the edge's expiry (0: none), when Retained.
	ExpiresAtUnix int64 `json:"expiresAtUnix,omitempty"`
	Unpruneable   bool  `json:"unpruneable,omitempty"`
}

Retention records a result's retention edge: the record that keeps the result alive after its session. Retained false means the edge was dropped. An unpruneable edge never expires, and making an edge unpruneable also clears the result's own expiry.

func (Retention) FactKind() Kind

type Term ¶

type Term struct {
	Self   string      `json:"self"`
	Inputs []TermInput `json:"inputs"`
}

Term is an operation's self digest over its ordered structural inputs.

type TermFact ¶

type TermFact struct {
	Self   string      `json:"self"`
	Inputs []TermInput `json:"inputs"`
	Output string      `json:"output"`
}

TermFact announces one term restored at boot. Inputs and Output name equivalence classes by one representative digest each: the smallest digest of the class. It is sent after every Class fact of the same boot.

func (TermFact) FactKind() Kind

type TermInput ¶

type TermInput struct {
	Digest     string     `json:"digest"`
	Provenance Provenance `json:"provenance"`
}

TermInput is one input of a term: a digest of the input's equivalence class and the input's provenance.

type TermUse ¶

type TermUse string

TermUse says how a teach used its term.

const (
	// TermUseReused: the result was already associated with the term.
	TermUseReused TermUse = "reused"
	// TermUseAssociated: the result was newly associated with an existing
	// congruent term.
	TermUseAssociated TermUse = "associated"
	// TermUseCreated: the teach created the term.
	TermUseCreated TermUse = "created"
)