remotecache

type Adapter interface {
	// CacheIdentity returns the engine cache's identity and generation.
	CacheIdentity() (cacheID string, generation uint64)
	// Export captures the requested roots and calls consume exactly once,
	// while the captured chains stay open. The export's Bundle is nil when no
	// root survived. The chains are released when consume returns. known are
	// the rows the service merged over this connection: an export sends
	// those as held rows.
	Export(ctx context.Context, req protocol.Export, known *dagql.KnownRows, consume func(context.Context, Export) error) error
	// Merge merges a bundle of the service's values into the cache. id is
	// the service's request ID, for logs. known are the rows the service
	// merged over this connection: the rows a committed merge lands on join
	// them, since the service holds the records it sent.
	Merge(ctx context.Context, id uint64, req protocol.Merge, known *dagql.KnownRows) (protocol.Merged, error)
	// OfferParts places offered parts on the cache's entries by number.
	OfferParts(ctx context.Context, req protocol.Offer) (protocol.Offered, error)
	// TakeRenewalRequest waits for the next read that needs fresh download
	// addresses; ReplyRenewal answers it.
	TakeRenewalRequest(ctx context.Context) (*dagql.RenewalRequest, error)
	ReplyRenewal(dagql.RenewalReply) dagql.RenewalReplyDisposition
	// StartLookups starts queuing the cache's lookup misses for this
	// connection, with nothing asked yet, and StopLookups stops it.
	StartLookups()
	StopLookups()
	// TakeLookupMisses waits for the cache's next misses, at most limit,
	// lingering up to linger after the first for more. dropped counts the
	// misses a full queue refused since the last take.
	TakeLookupMisses(ctx context.Context, limit int, linger time.Duration) (misses []dagql.RemoteMiss, dropped uint64, err error)
	// SettleState returns the engine's side of settling with the service,
	// and a channel closed when it next changes.
	SettleState() (SettleState, <-chan struct{})
	// Settled records the service's Settled for a settle of period that
	// listed sessions.
	Settled(period uint64, sessions []protocol.SettleSession)
}

type BlobSource interface {
	ReadBlob(ctx context.Context, dgst digest.Digest) (io.ReadCloser, int64, error)
}

type Config struct {
	// URL is the service's base URL; Run dials protocol.EnginePath under it.
	URL string
	// Token is the engine token, sent as the Basic username.
	Token string
	// EngineVersion and EngineName are sent in hello.
	EngineVersion string
	EngineName    string
	// Logger receives the connection's warnings and errors. Nil discards.
	Logger *slog.Logger
	// Lookups asks the service for the calls the engine's cache misses. The
	// engine always sets it; a test that serves no lookups leaves it off.
	Lookups bool
}

type Export struct {
	// Bundle is nil when no root survived.
	Bundle  *dagql.ValueBundle
	Skipped []protocol.SkippedRoot
	// Blobs reads the bundle's layer blobs for upload.
	Blobs BlobSource
	// Rows are the rows the bundle carries in full and as held rows, for
	// known once the service says whether it merged them.
	Rows dagql.ExportedRows
}

type SettleState struct {
	// Period is the engine's current idle period (protocol.Open).
	Period uint64
	// Live is set while a session is live.
	Live bool
	// Sessions are the ended sessions no Settled has covered.
	Sessions []protocol.SettleSession
	// Settled is set once a Settled covered Period.
	Settled bool
	// TimedOut is set once the engine gave up waiting to settle after its
	// last session ended, until a session starts again.
	TimedOut bool
	// Claims are the sessions that started under a Dagger Cloud claim,
	// sorted by session ID (protocol.Claims): those live, and those ended
	// that no Settled has covered.
	Claims []protocol.SessionClaim
}