internal/pkg: consolidate cache attributes

This makes the interface stable.

Signed-off-by: Ophestra <cat@gensokyo.uk>

internal/pkg/pkg.go

@@ -279,7 +279,7 @@ func (c *common) GetMessage() message.Msg { return c.cache.msg }
 
 // GetJobs returns the preferred number of jobs to run, when applicable. Its
 // value must not affect cure outcome.
-func (c *common) GetJobs() int { return c.cache.jobs }
+func (c *common) GetJobs() int { return c.cache.attr.Jobs }
 
 // GetWorkDir returns a pathname to a directory which [Artifact] is expected to
 // write its output to. This is not the final resting place of the [Artifact]
@@ -741,10 +741,8 @@ type Cache struct {
 
 	// Directory where all [Cache] related files are placed.
 	base *check.Absolute
-	// Immutable cure options set by [Open].
-	flags int
-	// Immutable job count, when applicable.
-	jobs int
+	// Immutable [CacheAttr] populated by [Open].
+	attr CacheAttr
 
 	// Must not be exposed directly.
 	irCache
@@ -1449,7 +1447,7 @@ func (c *Cache) openFile(
 	ctx context.Context,
 	f FileArtifact,
 ) (r io.ReadCloser, err error) {
-	if kc, ok := f.(KnownChecksum); c.flags&CAssumeChecksum != 0 && ok {
+	if kc, ok := f.(KnownChecksum); c.attr.Flags&CAssumeChecksum != 0 && ok {
 		c.checksumMu.RLock()
 		r, err = os.Open(c.base.Append(
 			dirChecksum,
@@ -2141,7 +2139,7 @@ func (c *Cache) cure(a Artifact, curesExempt, rebuild bool) (
 			checksums,
 		)
 
-		if c.flags&CAssumeChecksum != 0 {
+		if c.attr.Flags&CAssumeChecksum != 0 {
 			c.checksumMu.RLock()
 			checksumFi, err = os.Stat(checksumPathname.String())
 			c.checksumMu.RUnlock()
@@ -2210,7 +2208,7 @@ func (c *Cache) cure(a Artifact, curesExempt, rebuild bool) (
 		}
 		r, err = f.Cure(&RContext{common{ctx, c}})
 		if err == nil {
-			if checksumPathname == nil || c.flags&CValidateKnown != 0 {
+			if checksumPathname == nil || c.attr.Flags&CValidateKnown != 0 {
 				h := sha512.New384()
 				hbw := c.getWriter(h)
 				_, err = io.Copy(w, io.TeeReader(r, hbw))
@@ -2227,7 +2225,7 @@ func (c *Cache) cure(a Artifact, curesExempt, rebuild bool) (
 					if checksumPathname == nil {
 						checksum = unique.Make(Checksum(buf[:]))
 						checksums = Encode(Checksum(buf[:]))
-					} else if c.flags&CValidateKnown != 0 {
+					} else if c.attr.Flags&CValidateKnown != 0 {
 						if got := Checksum(buf[:]); got != checksum.Value() {
 							err = &ChecksumMismatchError{
 								Got:  got,
@@ -2319,7 +2317,7 @@ func (c *Cache) cure(a Artifact, curesExempt, rebuild bool) (
 			return
 		}
 		extern := externChecksum != zeroChecksum
-		shallow := extern && c.flags&CExternShallow != 0
+		shallow := extern && c.attr.Flags&CExternShallow != 0
 
 		inputs := a.Inputs()
 		f := FContext{t, make(map[Artifact]cureRes, len(inputs))}
@@ -2383,7 +2381,7 @@ func (c *Cache) cure(a Artifact, curesExempt, rebuild bool) (
 			substitutes,
 		)
 
-		if !rebuild && c.flags&CIgnoreSubstitutes == 0 {
+		if !rebuild && c.attr.Flags&CIgnoreSubstitutes == 0 {
 			var substituteChecksum unique.Handle[Checksum]
 			substituteChecksum, err = c.loadSubstitute(substitute)
 			if err != nil {
@@ -2677,6 +2675,20 @@ var (
 	ErrWouldPromote = errors.New("operation would promote unextended cache")
 )
 
+// CacheAttr holds the attributes that will be applied to a new [Cache] opened
+// by [Open].
+type CacheAttr struct {
+	// Concurrent cures of a [FloodArtifact] dependency graph.
+	Cures int
+	// Options affecting [Cache] behaviour.
+	Flags int
+	// Preferred job count, when applicable.
+	Jobs int
+
+	// Omit the [lockedfile] lock.
+	skipLock bool
+}
+
 // Open returns the address of a newly opened instance of [Cache].
 //
 // Concurrent cures of a [FloodArtifact] dependency graph is limited to the
@@ -2693,20 +2705,8 @@ var (
 func Open(
 	ctx context.Context,
 	msg message.Msg,
-	flags, cures, jobs int,
 	base *check.Absolute,
-) (*Cache, error) {
-	return open(ctx, msg, flags, cures, jobs, base, true)
-}
-
-// open implements Open but allows omitting the [lockedfile] lock when called
-// from a test. This is used to simulate invalid states in the test suite.
-func open(
-	ctx context.Context,
-	msg message.Msg,
-	flags, cures, jobs int,
-	base *check.Absolute,
-	lock bool,
+	attr *CacheAttr,
 ) (*Cache, error) {
 	openMu.Lock()
 	defer openMu.Unlock()
@@ -2716,11 +2716,15 @@ func open(
 		panic("attempting to open cache with incomplete variant setup")
 	}
 
-	if cures < 1 {
-		cures = runtime.NumCPU()
+	if attr == nil {
+		attr = new(CacheAttr)
 	}
-	if jobs < 1 {
-		jobs = runtime.NumCPU()
+
+	if attr.Cures < 1 {
+		attr.Cures = runtime.NumCPU()
+	}
+	if attr.Jobs < 1 {
+		attr.Jobs = runtime.NumCPU()
 	}
 
 	for _, name := range []string{
@@ -2742,9 +2746,8 @@ func open(
 	c := Cache{
 		parent: ctx,
 
-		cures: make(chan struct{}, cures),
-		flags: flags,
-		jobs:  jobs,
+		cures: make(chan struct{}, attr.Cures),
+		attr:  *attr,
 
 		msg:  msg,
 		base: base,
@@ -2761,7 +2764,7 @@ func open(
 	}
 	c.toplevel.Store(newToplevel(ctx))
 
-	if lock || !testing.Testing() {
+	if !attr.skipLock || !testing.Testing() {
 		if unlock, err := lockedfile.MutexAt(
 			base.Append(fileLock).String(),
 		).Lock(); err != nil {
@@ -2822,7 +2825,7 @@ func open(
 		}
 	} else if s := string(p); s == "" {
 		if extension != "" {
-			if flags&CPromoteVariant == 0 {
+			if attr.Flags&CPromoteVariant == 0 {
 				c.unlock()
 				return nil, ErrWouldPromote
 			}