feat(analyzer): analysis cache contract (MalysisCache interface + config) (#334)

analyzer/malysis_cache.go

@@ -0,0 +1,33 @@
+package analyzer
+
+import (
+	"context"
+
+	packagev1 "buf.build/gen/go/safedep/api/protocolbuffers/go/safedep/messages/package/v1"
+)
+
+// MalysisCache is the contract for a caching layer over package malware-analysis
+// verdicts. It lets a repeat analysis of the same package version be served
+// without a fresh backend round-trip, which is the dominant cost when
+// re-installing an already-screened dependency graph.
+//
+// Implementations are injected by the caller and may be backed by any store
+// (filesystem, sqlite, in-memory, ...). An implementation owns its own
+// expiry/TTL policy and must be safe for concurrent use by multiple goroutines.
+//
+// The cache stores and returns whatever verdicts it is given; the decision of
+// which verdicts are safe to cache (e.g. only ALLOW) belongs to the caller, not
+// the cache.
+type MalysisCache interface {
+	// Get returns the cached analysis result for the given package version.
+	// The boolean is false on a miss, which includes an absent or expired
+	// entry. A non-nil error indicates a backend failure; callers should treat
+	// it as a miss and fall back to a fresh analysis rather than failing the
+	// operation.
+	Get(ctx context.Context, pkg *packagev1.PackageVersion) (*PackageVersionAnalysisResult, bool, error)
+
+	// Set stores an analysis result for the given package version. Caching is
+	// best-effort: a non-nil error means the verdict could not be persisted and
+	// callers should continue without failing.
+	Set(ctx context.Context, pkg *packagev1.PackageVersion, result *PackageVersionAnalysisResult) error
+}